18.2 Visiting Files

C-x C-f

Visit a file (find-file).

C-x C-r

Visit a file for viewing, without allowing changes to it (find-file-read-only).

C-x C-v

Visit a different file instead of the one visited last (find-alternate-file).

C-x 4 f

Visit a file, in another window (find-file-other-window). Don’t alter what is displayed in the selected window.

C-x 5 f

Visit a file, in a new frame (find-file-other-frame). Don’t alter what is displayed in the selected frame.

M-x find-file-literally

Visit a file with no conversion of the contents.

Visiting a file means reading its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit.

To visit a file, type C-x C-f (find-file) and use the minibuffer to enter the name of the desired file. While in the minibuffer, you can abort the command by typing C-g. See File Names, for details about entering file names into minibuffers.

If the specified file exists but the system does not allow you to read it, an error message is displayed in the echo area. Otherwise, you can tell that C-x C-f has completed successfully by the appearance of new text on the screen, and by the buffer name shown in the mode line (see Mode Line). Emacs normally constructs the buffer name from the file name, omitting the directory name. For example, a file named /usr/rms/emacs.tex is visited in a buffer named ‘emacs.tex’. If there is already a buffer with that name, Emacs constructs a unique name; the normal method is to add a suffix based on the directory name (e.g., ‘<rms>’, ‘<tmp>’, and so on), but you can select other methods. See Uniquify.

To create a new file, just visit it using the same command, C-x C-f. Emacs displays ‘(New file)’ in the echo area, but in other respects behaves as if you had visited an existing empty file.

After visiting a file, the changes you make with editing commands are made in the Emacs buffer. They do not take effect in the visited file, until you save the buffer (see Saving). If a buffer contains changes that have not been saved, we say the buffer is modified. This implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.

If you visit a file that is already in Emacs, C-x C-f switches to the existing buffer instead of making another copy. Before doing so, it checks whether the file has changed since you last visited or saved it. If the file has changed, Emacs offers to reread it.

If you try to visit a file larger than large-file-warning-threshold (the default is 10000000, which is about 10 megabytes), Emacs asks you for confirmation first. You can answer y to proceed with visiting the file. Note, however, that Emacs cannot visit files that are larger than the maximum Emacs buffer size, which is limited by the amount of memory Emacs can allocate and by the integers that Emacs can represent (see Buffers). If you try, Emacs displays an error message saying that the maximum buffer size has been exceeded.

If the file name you specify contains shell-style wildcard characters, Emacs visits all the files that match it. (On case-insensitive filesystems, Emacs matches the wildcards disregarding the letter case.) Wildcards include ‘?’, ‘*’, and ‘[…]’ sequences. To enter the wild card ‘?’ in a file name in the minibuffer, you need to type C-q ?. See Quoted File Names, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing find-file-wildcards.

If you visit the wrong file unintentionally by typing its name incorrectly, type C-x C-v (find-alternate-file) to visit the file you really wanted. C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified). When C-x C-v reads the file name to visit, it inserts the entire default file name in the buffer, with point just after the directory part; this is convenient if you made a slight error in typing the name.

If you visit a file that is actually a directory, Emacs invokes Dired, the Emacs directory browser. See Dired. You can disable this behavior by setting the variable find-file-run-dired to nil; in that case, it is an error to try to visit a directory.

Files which are actually collections of other files, or file archives, are visited in special modes which invoke a Dired-like environment to allow operations on archive members. See File Archives, for more about these features.

If you visit a file that the operating system won’t let you modify, or that is marked read-only, Emacs makes the buffer read-only too, so that you won’t go ahead and make changes that you’ll have trouble saving afterward. You can make the buffer writable with C-x C-q (read-only-mode). See Misc Buffer.

If you want to visit a file as read-only in order to protect yourself from entering changes accidentally, visit it with the command C-x C-r (find-file-read-only) instead of C-x C-f.

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window. The window that was selected before C-x 4 f continues to show the same buffer it was already showing. If this command is used when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file. See Windows.

C-x 5 f (find-file-other-frame) is similar, but opens a new frame, or selects any existing frame showing the specified file. See Frames.

On graphical displays, there are two additional methods for visiting files. Firstly, when Emacs is built with a suitable GUI toolkit, commands invoked with the mouse (by clicking on the menu bar or tool bar) use the toolkit’s standard file selection dialog instead of prompting for the file name in the minibuffer. On GNU/Linux and Unix platforms, Emacs does this when built with GTK, LessTif, and Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. For information on how to customize this, see Dialog Boxes.

Secondly, Emacs supports drag and drop: dropping a file into an ordinary Emacs window visits the file using that window. As an exception, dropping a file into a window displaying a Dired buffer moves or copies the file into the displayed directory. For details, see Drag and Drop, and Misc Dired Features.

On text-mode terminals and on graphical displays when Emacs was built without a GUI toolkit, you can visit files via the menu-bar ‘File’ menu, which has a ‘Visit New File’ item.

Each time you visit a file, Emacs automatically scans its contents to detect what character encoding and end-of-line convention it uses, and converts these to Emacs’s internal encoding and end-of-line convention within the buffer. When you save the buffer, Emacs performs the inverse conversion, writing the file to disk with its original encoding and end-of-line convention. See Coding Systems.

If you wish to edit a file as a sequence of ASCII characters with no special encoding or conversion, use the M-x find-file-literally command. This visits a file, like C-x C-f, but does not do format conversion (see Format Conversion in the Emacs Lisp Reference Manual), character code conversion (see Coding Systems), or automatic uncompression (see Compressed Files), and does not add a final newline because of require-final-newline (see Customize Save). If you have already visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead.

Two special hook variables allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in find-file-not-found-functions; this variable holds a list of functions, which are called one by one (with no arguments) until one of them returns non-nil. This is not a normal hook, and the name ends in ‘-functions’ rather than ‘-hook’ to indicate that fact.

Successful visiting of any file, whether existing or not, calls the functions in find-file-hook, with no arguments. This variable is a normal hook. In the case of a nonexistent file, the find-file-not-found-functions are run first. See Hooks.

There are several ways to specify automatically the major mode for editing the file (see Choosing Modes), and to specify local variables defined for that file (see File Variables).